事件推送（2025‑05‑15 版）

注册回调即可实时接收机器人事件报警，新增集团客户推送支持。

• 兼容性：2025‑05‑15（含）之后新建或重新保存的订阅将采用本文描述的 新顶级字段格式；
• 已生效的旧订阅保持两级结构（appId + payload），功能不受影响。
• 新顶级字段（与 appId、payload 同级）：
• 集团客户：同一集团下的多租户可以在一个回调地址统一接收推送，通过新增顶级字段区分不同产品与业务。

回调注册要求

1. 语言：符合 IETF BCP 47（如 en-US、zh-CN）。

2. 回调：

   • url 例如 https://{{host}}/callback，HTTP 方法 POST。
   • appId 例如 24416c36-d9c7-4d74-a047-d6ca461fxxxx（用于鉴权）。

示例（新格式）

curl -X POST "https://{{host}}/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "24416c36-d9c7-4d74-a047-d6ca461fxxxx",
    "payload": {
      "serialNumber": "ITEST00-0000-000-XXXX",
      "modelTypeCode": "Scrubber 50H",
      "content": {
        "incidentId": "74bbc189-3313-4665-8204-9fbe45dfxxxx",
        "incidentCode": "1011",
        "incidentName": "Clean water full",
        "incidentLevel": "H2",
        "incidentStatus": 1,
        "startTime": "2025-05-15T02:09:28Z",
        "endTime": "",
        "taskId": "..."
      }
    },
    "messageTypeId": 1,
    "productId": "ITEST00-0000-000-XXXX",
    "messageId": "ITEST00-0000-000-XXXX:1:74bbc189-3313-4665-8204-9fbe45dfxxxx",
    "traceId": "34c2e8f816414f318b7419b6a9c91d8f",
    "messageTimestamp": 1715740800000
}'

顶级字段说明

字段	类型	描述
appId	String	用于鉴权，保持不变
payload	Object	业务数据，结构与旧版保持一致
messageTypeId	Int	推送类型：1 事件，2 任务报告，3 排班任务
productId	String	机器人序列号（SN）
messageId	String	全局唯一消息 ID，格式 {productId}:{messageTypeId}:{businessId}
traceId	String	请求链路追踪 ID
messageTimestamp	Long	推送触发时间戳（毫秒）

参数描述：

字段名称	字段类型	字段描述	示例
payload.serialNumber	String	机器人序列号	"TEST00-0000-000-XXXX"
payload.modelTypeCode	String	机器人型号代码	"Scrubber 50H"
payload.content	Object	事件内容
payload.content.incidentCode	String	事件代码	"1011"
payload.content.incidentName	String	事件名称	"Clean water full"
payload.content.incidentLevel	String	事件等级	"H2"
payload.content.incidentId	String	事件ID	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.incidentStatus	int	事件状态，1 报警，0 恢复	1
payload.content.startTime	String	事件开始时间，UTC时间	"2023-01-14T02:09:28Z"
payload.content.endTime	String	事件结束时间，UTC时间。如果事件未恢复，结束时间为空字符串	"2023-01-14T02:09:28Z" 或 ""
payload.content.taskId	String	事件发生时，机器人正在执行的任务id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.subTaskId	String	事件发生时，机器人正在执行的子任务id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.taskInstanceId	String	事件发生时，机器人正在执行的任务实例id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.taskName	String	事件发生时，机器人正在执行的任务名称	"task1"
payload.content.mapId	String	事件发生时，机器人所在地图的id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.mapName	String	事件发生时，机器人所在的地图名称	"map1"
payload.content.navInstanceId	String	事件发生时，机器人正在执行的导航实例id	"da4b1ca9-dbfe-4dd2-bcbe-715c00904f0b"
payload.content.navName	String	事件发生时，机器人正在执行的导航点名称	"hop"
payload.content.incidentLevel：

值	名称	描述
H0	事件	这不是报警，仅是事件通知
H1	状态	埋点统计
H2	状态	机器人的常规状态，用户无需指导即可解决
H3	警告	不影响机器人任务，用户可以解决
H4	协助，问题	影响机器人任务，用户可以解决
H5	隐患	不影响机器人任务，用户无法解决
H6	故障	影响机器人任务，用户无法解决
H7	质量问题	严重故障